Skip to main content

Project Structure

This document provides guidelines for the organization of the Meall an Óige project, describing what types of files should be placed in each directory.

Root Directory​

The root directory should contain configuration files and application entry points:

  • App Entry Point: Main application setup (App.js) that configures providers, navigation, and global settings
  • Build Configuration: Files that control how the app is built and bundled (babel.config.js, metro.config.js)
  • Project Configuration: Files defining project metadata, dependencies, and scripts (package.json, app.json)
  • Editor Configuration: Settings for development environments (.vscode/, jsconfig.json)
  • Deployment Configuration: Settings for build and deployment processes (eas.json)
  • Documentation: Project-level documentation and readme files

Scripts Directory​

Should contain utility scripts that assist in development, build processes, or maintenance tasks:

  • Asset Processing: Scripts for optimizing or converting assets (like audio/image conversion)
  • Data Management: Tools for data migration, generation, or cleanup
  • Build Helpers: Scripts that assist in the build or deployment process
  • Development Utilities: Tools that assist during development

Source Code Structure (src/)​

Assets Directory​

Should store all static assets required by the application:

  • Images: UI elements, icons, backgrounds, and character graphics
  • Audio: Sound effects, voice recordings, and background music
  • Fonts: Custom typography files
  • Animations: Animation resources and assets

Assets should be organized by purpose or feature area (e.g., tutorial assets, game-specific assets) rather than file type.

Components Directory​

Should contain React components organized by feature or purpose:

  • Common Components: Reusable UI elements used across the application (buttons, loaders, modals)
  • Feature-Specific Components: Components tied to specific features or sections
  • Layout Components: Components that handle page structure and layout
  • Form Components: Input fields, validation, and form-related components

Components should be organized hierarchically with related components grouped together. Complex components should be broken down into smaller subcomponents when appropriate.

Constants Directory​

Should define application-wide constants and configuration values:

  • Feature Flags: Toggle values for enabling/disabling features
  • API Endpoints: Service URLs and endpoint definitions
  • Configuration Values: Application settings and parameters
  • Enumerations: Sets of related constant values representing states or options
  • Default Settings: Default configuration values

Constants should be organized by domain and exported as objects or individual values with clear naming conventions.

Fonts Directory​

Should contain custom font files used throughout the application:

  • Typography Files: Font files in appropriate formats (TTF, OTF)
  • Font License Files: Documentation of font usage rights

Hooks Directory​

Should contain custom React hooks that encapsulate reusable logic:

  • UI Logic: Hooks for handling UI state and interactions
  • Data Fetching: Hooks for retrieving and managing remote data
  • Media Handling: Hooks for audio, video, or image processing
  • Device Features: Hooks that interface with platform capabilities
  • Animation: Hooks for managing animations and transitions

Hooks should be focused on a single concern and named with the 'use' prefix according to React conventions.

Locales Directory​

Should contain internationalization and localization resources:

  • Translation Files: JSON files containing translated strings for supported languages
  • Locale Configuration: Settings for date, time, and number formatting

Partials Directory​

Should contain partial implementations or helper modules that don't fit elsewhere:

  • Data Transformers: Functions that transform or process data for specific features
  • Feature-Specific Utilities: Helper functions tied to particular application features
  • Service Integration: Code that interfaces with specific external services

Screens Directory​

Should contain top-level screen components organized by application section:

  • Authentication Screens: Login, registration, and account management
  • Feature Screens: Main feature areas of the application
  • Navigation Containers: Screen containers that manage navigation within sections
  • Settings Screens: Configuration and preference management

Screen components should focus on layout and composition of smaller components rather than containing complex logic.

State Directory​

Should contain state management code:

  • Context Providers: React context definitions and provider components
  • Reducers: State management logic for complex state
  • Actions: Definitions of state changes and events
  • Selectors: Functions for accessing and deriving state
  • Service Configuration: Setup for external services (e.g., Supabase)

State should be organized by domain with clear separation of concerns.

Styles Directory​

Should contain styling definitions and theme configuration:

  • Color Palettes: Color definitions and themes
  • Typography: Text styling and font configurations
  • Layout Utilities: Spacing, sizing, and positioning helpers
  • Theme Definitions: Complete theme objects for application styling

Utils Directory​

Should contain pure utility functions that are domain-agnostic:

  • Data Processing: Functions for manipulating data structures
  • Formatting: Text, number, and date formatting utilities
  • Validation: Input validation and verification functions
  • Network Utilities: Functions for handling API requests and responses
  • Math and Calculations: Helper functions for computations

Utility functions should be pure, focused on a single concern, and thoroughly tested.

Architectural Guidelines​

When organizing the Meall an Óige codebase:

  1. Feature Cohesion: Keep related files together, especially for feature-specific code
  2. Separation of Concerns: Distinguish between UI components, business logic, and state management
  3. Reusability: Extract common patterns into shared components and hooks
  4. Naming Conventions: Use consistent and descriptive names for files and directories
  5. Module Boundaries: Establish clear interfaces between different parts of the application
  6. Progressive Disclosure: Organize code so that the most important or frequently used files are most accessible

These guidelines should help maintain a consistent and maintainable codebase as the application evolves.